'\" t
.\"     Title: icon2gif
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 2 May 2012
.\"    Manual: GIFLIB Documentation
.\"    Source: GIFLIB
.\"  Language: English
.\"
.TH "ICON2GIF" "1" "2 May 2012" "GIFLIB" "GIFLIB Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
icon2gif \- dump GIF data in a textual format, or undump it to a GIF
.SH "SYNOPSIS"
.HP \w'\fBicon2gif\fR\ 'u
\fBicon2gif\fR [\-v] [\-a] [\-d] [\-t\ \fItranslation\-table\fR] [\-h] [\fIgif\-file\fR]
.SH "OPTIONS"
.PP
A program to convert a series of editable text GIF icon specifications and named GIF files into a multi\-image GIF, usable as a graphic resource file\&. It can also dump existing GIFs in this format\&.
.PP
If no gif\-file is given, icon2gif will try to read a text input from stdin\&.
.SH "SPECIFICATION SYNTAX"
.PP
Here is a syntax summary in informal BNF\&. The token `NL\*(Aq represents a required newline\&.
.sp
.if n \{\
.RS 4
.\}
.nf
<gif\-spec> ::= <header\-block> <image\-block>\&.\&.\&.

<header\-block> ::= <header\-declaration>\&.\&.\&.

<header\-declaration ::=
		| screen width <digits> NL
		| screen height <digits> NL
		| screen colors <digits> NL
		| screen background <digits> NL
		| screen map <color\-table> NL

<color\-table> ::= <color\-declaration>\&.\&.\&. end NL

<color\-declaration> ::= rgb <digits> <digits> <digits> is <key> NL

<image\-block> ::= include <file\-name> NL
		| image NL
			<image\-declaration>\&.\&.\&.
			<raster\-picture>
			[ <extension> ]

<image\-declarations> ::= image top <digits> NL
			| image left <digits> NL
			| image interlaced NL
			| image map <color\-table> NL
			| image bits <digits> by <digits> NL <raster\-block>

<extension> := <comment> NL <extension\-block> NL end NL
		| <plaintext> NL <extension\-block> NL end NL
		| extension <hex\-digits> NL <extension\-block> NL end NL
.fi
.if n \{\
.RE
.\}
.PP
If the semantics of the `screen height\*(Aq, `screen width\*(Aq, `screen background\*(Aq, `image top\*(Aq, `image left\*(Aq declarations aren\*(Aqt obvious to you, what are you doing with this software?
.PP
A color table declares color indices (in ascending order from 0) and assiciates them with key characters\&. These characters can later be used in raster blocks\&. As these must be printable and non\-whitespace, you can only specify 94 colors per icon\&. Life is like that sometimes\&.
.PP
A raster block is just a block of key characters\&. It should be sized correctly for the `image bits\*(Aq declaration that leads it\&.
.PP
The `comment\*(Aq or `plaintext\*(Aq keywords lead defined GIF89 extension record data (the other two GIF89 types, graphics control and application block, are not yet supported)\&. You can also say `extension\*(Aq followed by a hexadecimal record type\&. All of these extension declarations must be followed by an extension block, which is terminated by the keyword `end\*(Aq on its own line\&.
.PP
An extension block is a series of text lines, each interpreted as a string of bytes to fill an argument block (the terminating newline is stripped)\&. Text may include standard C\-style octal and hex escapes preceded by a backslash\&.
.PP
All <digits> tokens are interpreted as decimal numerals; <hex\-digits> tokens are interpreted as two hex digits (a byte)\&. All coordinates are zero\-origin with the top left corner (0,0)\&. Range checking is weak and signedness checking nonexistent; caveat hacker!
.PP
In general, the amount of whitespace and order of declarations within a header or image block is not significant, except that a raster picture must immediately follow its `image bits\*(Aq bits declaration\&.
.PP
The `include\*(Aq declaration includes a named GIF as the next image\&. The global color maps of included GIFs are merged with the base table defined by any `screen color\*(Aq declaration\&. All images of an included multi\-image GIF will be included in order\&.
.PP
Comments may be preceded with `#\*(Aq and will be ignored\&.
.SH "OPTIONS"
.PP
\-v
.RS 4
Verbose mode (show progress)\&. Enables printout of running scan lines\&.
.RE
.PP
\-d
.RS 4
Dump the input GIF file(s) into the text form described above\&.
.RE
.PP
\-t
.RS 4
Specify name characters to use when dumping raster blocks\&. Only valid with \-d option\&.
.RE
.PP
\-h
.RS 4
Print one line of command line help, similar to Usage above\&.
.RE
.SH "BUGS"
.PP
Because there are only 94 characters unambiguously usable for raster blocks, an attempt to dump a GIF with a larger color map will fail\&.
.PP
Error checking is rudimentary\&.
.SH "EXAMPLE:"
.PP
A sample icon file called `sample\&.ico\*(Aq is included in the pic directory of the GIFLIB source distribution\&.
.SH "AUTHOR"
.PP
Eric S\&. Raymond
esr@thyrsus\&.com
